#####################################################################################
# This HOWTO describes how to install RHEL4 U3 onto a hard drive in such a way that
# this disk is bootable using an Intel iSCSI NIC. This document describes two methods
# to accomplish this: Remote Install and Local Install. Remote Install is the process
# of installing directly to a hard drive in an iSCSI storage array. This disk is
# referred to as an iSCSI LU. Local Install is the process of installing to a local 
# disk drive and then transferring this disk drive or OS image to an iSCSI Target. 
# This document will not cover how to deploy the disk drive onto the iSCSI Target or
# how to configure the target as those steps can vary widely. The Remote Install and 
# Local Install methods are mostly the same. It is noted where there are differences.
#
# This process is neither supported by the installer nor the distribution natively,
# this solution is a series of workarounds. The user should have a strong technical 
# understanding of iSCSI, the installer, the Linux boot process, the RHEL4 
# installation process and SCSI device enumeration. For more information on SCSI 
# device enumeration, refer to Appendix A in the end of this document. With this 
# knowledge the user should be able to work through any encountered issues.                   
#####################################################################################

This process has two phases.
1) Creating the Driver Update Media (DUM)   
	This involves copying the iSCSI module, its dependencies and the utilities 
	needed for installation onto an update disk. The disk can be an IDE floppy,
	USB floppy or USB flash drive.

2) Installation to the iSCSI target LU
	This consists of two parts; pre-install and post-install.

#####################################################################################
Prerequisites
#####################################################################################
This document explains how to install using source and tools provided on the RHEL4 U3 
CDs. If the user wants to use newer code (kernel src, development packages, initiator 
source, kernel modules, etc...) it is the user's responsibility to obtain the newer 
code and alter this process accordingly. A user with the following prerequisites can 
install and boot RHEL4 U3 on an iSCSI Target LU.

1) A RHEL4 U3 build machine
	To ensure module compatibility the architecture of the build machine should
	match both the install media and the diskless system with which you intend to 
	connect to the iSCSI Target LU. This means that if you will be doing a 
	diskless boot on an x86_86 system your build machine will need be have an 
	x86_64 architecture. The install CDs will also need to be for the x86_64 
	architecture.

2) iSCSIBoot.tar.gz
	Provided by Intel.

3) Install Media
	A blank 3.5' floppy disk, or a USB flash drive.

4) The iSCSI Target LUN (Boot LUN) 
        This information is important to know in advance so that grub can be
        configured correctly.

###################################################################################
Phase I  - Creating the Drivers and Utilities Media (DUM)
###################################################################################
1) Copy and untar iSCSIBoot.tar.gz on the build machine.
	a) cp iSCSIBoot.tar.gz /home
        b) cd /home
        c) tar -zxvf iSCSIBoot.tar.gz

2) Compile iscsiboot/iscsi_boot_util.c statically.
        gcc -static -Wall iscsi_boot_util.c -o iscsi_boot_util

3) Install the following RPM and copy modules to preinstall directory.
	a) rpm -ivh kernel-2.6.9-34.EL.i686.rpm, from the RHEL4 U3 CD2
        b) cp -f \
            /lib/modules/2.6.9-34.EL/kernel/drivers/scsi/scsi_transport_iscsi.ko \
	    /lib/modules/2.6.9-34.EL/kernel/drivers/scsi/iscsi_sfnet/iscsi_sfnet.ko \
	    /lib/modules/2.6.9-34.EL/kernel/crypto/crc32c.ko \
	    /lib/modules/2.6.9-34.EL/kernel/crypto/md5.ko \
	    /lib/modules/2.6.9-34.EL/kernel/lib/libcrc32c.ko  \
            /home/iSCSIBoot/preinstall/

4) Copy media onto the DUM
	a) Attach the DUM and mount it if necessary.
	b) cp -fr /home/iSCSIBoot/iscsi_boot_util /home/iSCSIBoot/preinstall  \
	    /home/iSCSIBoot/postinstall  <DUM mount point>
	c) Unmount if necessary and remove the DUM

######################################################################################
Phase II - Installation to the iSCSI disk
######################################################################################
NOTE: This assumes you have flashed and configured the iSCSI firmware to connect to
the target and iSCSI firmware was able to connect to the iSCSI target.

NOTE: If you are using USB flash drive/USB floppy as DUM, it must be attached prior to
this step. If you're performing a Local Install, make sure the local disk is connected. 

1) Begin installation with the option "linux updates".

2) Continue until the "Update Disk Source" screen.
        a) Press Ctrl+Alt+f2 to switch to command line mode.
        b) Make a mount point directory and mount the DUM. (The mount point can
           be anywhere but /mnt). Depending on the DUM media type, these are the 
 	     instructions:
             IDE floppy
               mkdir /mnt/floppy /tmp/iscsi
               mount /dev/fd0 /mnt/floppy
               cp -fr /mnt/floppy/* /tmp/iscsi
               umount /dev/fd0

             USB Floppy/USB flash drive
	       To mount a USB device you must understand which /dev node the kernel will
                use to represent the DUM. To do this run "dmesg" and examine the output.
                Look for the text which shows your USB device's registration with the system.
                Determine which sdX device is associated with your device.

               Next run "cat /proc/partitions", the output should look similar to this,

		Major    Minor    #blocks    Name
                7        0        <x>        loop0
                8        0        <x>        sda

	        Using the /dev node determine the minor number for your USB device.

               Mount the USB device.

		mkdir /mnt/usb /tmp/iscsi

		mknod /dev/sdX b 8 <minor#>

                cp -fr /mnt/usb/* /tmp/iscsi
                DO NOT unmout/remove USB floppy/USB flash drive at this point.

        c) Run the iscsipreinstall script from the mount point.
               /tmp/iscsi/preinstall/iscsipreinstall
        d) Run "dmesg" again to verify that discovery occurred correctly. It should show
           that drives were recently discovered. Note the LUNs and discovered SCSI device 
           nodes. This information needed to set grub configuration files.
        e) Press Ctrl+Alt+F1 and select "Back".
        f) Continue with the installation.

NOTE: When partitioning the iSCSI LUs, ensure that the boot partition is not
distributed across physical partitions on different iSCSI LUs. The Intel iSCSI Option
ROM will only access one iSCSI LU and if /boot is distributed across multiple LUs, it
will not be visible during the boot process.

3) Configure the boot order
        a) On the "Boot Loader Configuration" screen, select "Configure advanced boot
           loader options".
        b) Change the drive order so that the target disk is on the top of the list.
        c) Continue with the remainder of the installation.
        d) When the installation is complete DO NOT press "Reboot".

4) Make some final post install changes
        a) Press Ctrl-Alt-F2 to switch back to the console.
        b) Alter grub settings
           Modify the device.map and grub.conf files so that they have the correct
           device node listed. Refer to Appendix A for more information on SCSI device 
           enumeration. 
            /mnt/sysimage/boot/grub/device.map
                (hd0)   <SCSI device node for Boot LUN>
            /mnt/sysimage/boot/grub/grub.conf
                #boot=<SCSI device node for Boot LUN>
        c) Run the post install script and unmount the DUM.
                /tmp/iscsi/postinstall/iscsipostinstall

5) Ensure the network is not shutdown during halt
        a) Edit the /mnt/sysimage/etc/init.d/halt and scroll to the bottom.
        b) Change the line stating HALTARGS="-i -d" to HALTARGS="-d"

6) Return to the GUI and reboot
        a) Press Ctrl+Alt+F7 and then select "Reboot"
        b) Remove the installation media and DUM

7) On your first boot, if Kudzu asks you if you'd like to configure your adapters,
   please select to "ignore" the device.


Appendix A
==========
The iSCSI LUs are discovered as SCSI device nodes. The enumeration of SCSI devices 
is dynamic. The SCSI subsystem creates device nodes in the order that they are 
discovered, starting with /dev/sda and incrementing alphabetically. In the case of 
iSCSI LU enumeration, local SCSI devices such as disks or USB devices affect this 
process. If a device node is created for a USB device before iSCSI discovery occurs 
the USB device will be represented by /dev/sda and the iSCSI LUs will begin with 
/dev/sdb. However, if you were to reboot this system without the USB device the 
iSCSI LUs will begin with /dev/sda. It is important to configure grub correctly to 
point to the correct device node in order to boot from an iSCSI hard drive.

It is often the case when installing to an iSCSI LU that a device driven by the SCSI
subsystem is used for the install media. For example, using a USB flash drive for
the DUM. As stated above this will affect how grub should be configured when
installing.

Here is an example of how iSCSI device node mappings might differ between
installation and booting.

In this example the user is using a USB flash drive as a DUM. Since this device
is being used to copy files onto the system it is present before iSCSI discovery
occurs. However, when booting from the iSCSI Boot Disk no USB flash drive is
necessary and therefore it isn't attached.

Remote Installation:
USB flash drive or USB floppy                         /dev/sda
LUN 0                                                 /dev/sdb
LUN 1                                                 /dev/sdc

Booting:
LUN 0                                                 /dev/sda
LUN 1                                                 /dev/sdb

If the USB device is attached after booting, it will be enumerated as such,
USB flash drive or USB floppy                         /dev/sdc

It is also possible that there are other USB devices on the system, it is
users responsibility to find out if these will interfere with the device node mapping
during boot.

Appendix B
==========
After performing a Local Install on an IDE device the user will need to modify grub
so that when booting the root partition is identified as a SCSI device. When 
installing to a local IDE disk drive the device node used will be of the form 
/dev/hdX, but when this volume is exposed by the iSCSI target the initator will see 
the hard drive as a SCSI device and it will be represented as /dev/sdX. This change
must be made in the grub configuration file. This type of problem exposes the 
necessity that the user fully understand the concepts described in this document
as specifics may vary greatly.